<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>FAQ</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Beast">
<link rel="up" href="../design_choices.html" title="Design Choices">
<link rel="prev" href="comparison_to_zaphoyd_studios_we.html" title="Comparison to Zaphoyd Studios WebSocket++">
<link rel="next" href="../release_notes.html" title="Release Notes">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="comparison_to_zaphoyd_studios_we.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../design_choices.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../release_notes.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="beast.design_choices.faq"></a><a class="link" href="faq.html" title="FAQ">FAQ</a>
</h3></div></div></div>
<p>
        To set realistic expectations and prevent a litany of duplicate review statements,
        these notes address the most common questions and comments about Beast and
        other HTTP libraries that have gone through formal review.
      </p>
<div class="variablelist">
<p class="title"><b></b></p>
<dl class="variablelist">
<dt><span class="term"> "Beast requires too much user code to do anything!" </span></dt>
<dd><p>
              It is not the intention of the library to provide turn-key solutions
              for specific HTTP or WebSocket use-cases. Instead, it is a sensible
              protocol layering on top of Boost.Asio which retains the Boost.Asio
              memory management style and asynchronous model.
            </p></dd>
<dt><span class="term"> "Beast does not offer an HTTP server?" </span></dt>
<dd><p>
              Beast has a functional HTTP server in the example directory. The server
              supports both HTTP and WebSocket using synchronous and asynchronous
              shared or dedicated ports. In addition, the server supports encrypted
              TLS connections if OpenSSL is available, on dedicated ports. And the
              server comes with a "multi-port", a flexible single port
              which supports both encrypted and unencrypted connections, both HTTP
              and WebSocket, all on the same port. The server is not part of Beast's
              public interfaces, as that functionality is outside the scope of the
              library. The author feels that attempting to broaden the scope of the
              library will reduce its appeal for standardization.
            </p></dd>
<dt><span class="term"> "Beast does not offer an HTTP client?" </span></dt>
<dd><p>
              "I just want to download a resource using HTTP" is a common
              cry from users and reviewers. Such functionality is beyond the scope
              of Beast. Building a full featured HTTP client is a difficult task
              and large enough to deserve its own library. There are many things
              to deal with such as the various message body encodings, complex parsing
              of headers, difficult header semantics such as Range and Cache-Control,
              redirection, Expect:100-continue, connection retrying, domain name
              resolution, TLS, and much, much more. It is the author's position that
              Boost first needs a common set of nouns and verbs for manipulating
              HTTP at the protocol level; Beast provides that language.
            </p></dd>
<dt><span class="term"> "There's no HTTP/2 support yet!" </span></dt>
<dd>
<p>
              Many reviewers feel that HTTP/2 support is an essential feature of
              a HTTP library. The authors agree that HTTP/2 is important but also
              feel that the most sensible implementation is one that does not re-use
              the same network reading and writing interface for 2 as that for 1.0
              and 1.1.
            </p>
<p>
              The Beast HTTP message model was designed with the new protocol in
              mind and should be evaluated in that context. There are plans to add
              HTTP/2 in the future, but there is no rush to do so. Users can work
              with HTTP/1 now; we should not deny them that functionality today to
              wait for a newer protocol tomorrow. It is the author's position that
              there is sufficient value in Beast's HTTP/1-only implementation that
              the lack of HTTP/2 should not be a barrier to acceptance.
            </p>
<p>
              The Beast HTTP message model is suitable for HTTP/2 and can be re-used.
              The IETF HTTP Working Group adopted message compatibility with HTTP/1.x
              as an explicit goal. A parser can simply emit full headers after decoding
              the compressed HTTP/2 headers. The stream ID is not logically part
              of the message but rather message metadata and should be communicated
              out-of-band (see below). HTTP/2 sessions begin with a traditional HTTP/1.1
              Upgrade similar in fashion to the WebSocket upgrade. An HTTP/2 implementation
              can use existing Beast.HTTP primitives to perform this handshake.
            </p>
</dd>
<dt><span class="term"> "This should work with standalone-Asio!" </span></dt>
<dd>
<p>
              Beast uses more than Boost.Asio, it depends on various other parts
              of Boost. The standalone Asio is currently farther ahead than the Boost
              version. Keeping Beast maintained against both versions of Asio is
              beyond the resources of the author at the present time. Compatibility
              with non-Boost libraries should not be an acceptance criteria. Beast
              is currently designed to be a part of Boost: nothing more, nothing
              less. Looking at the bigger picture, it is the author's goal to propose
              this library for standardization. A logical track for achieving this
              is as follows:
            </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
                  Boost library acceptance.
                </li>
<li class="listitem">
                  Port to the Boost.Asio version of Networking-TS (This has to wait
                  until Boost's version of Asio is updated).
                </li>
<li class="listitem">
                  Wait for Networking-TS to become an official part of C++.
                </li>
<li class="listitem">
                  Port to the standard library versions of networking (gcc, clang,
                  msvc).
                </li>
<li class="listitem">
                  Develop proposed language (This can happen concurrently with steps
                  3 and 4)
                </li>
</ol></div>
</dd>
<dt><span class="term"> "You need benchmarks!" </span></dt>
<dd>
<p class="simpara">
              The energy invested in Beast went into the design of the interfaces,
              not performance. That said, the most sensitive parts of Beast have
              been optimized or designed with optimization in mind. The slow parts
              of WebSocket processing have been optimized, and the HTTP parser design
              is lifted from another extremely popular project which has performance
              as a design goal (see <a href="https://github.com/h2o/picohttpparser" target="_top">https://github.com/h2o/picohttpparser</a>).
            </p>
<p class="simpara">
              From: <a href="http://www.boost.org/development/requirements.html" target="_top">http://www.boost.org/development/requirements.html</a>
            </p>
<p class="simpara">
              "Aim first for clarity and correctness; optimization should be
              only a secondary concern in most Boost libraries."
            </p>
<p class="simpara">
              As the library matures it will undergo optimization passes; benchmarks
              will logically accompany this process. There is a small benchmarking
              program included in the tests which compares the performance of Beast's
              parser to the NodeJS reference parser, as well as some benchmarks which
              compare the performance of various Beast dynamic buffer implementations
              against Asio's.
            </p>
</dd>
<dt><span class="term"> "Beast is a terrible name!" </span></dt>
<dd>
<p>
              The name "Boost.Http" or "Boost.WebSocket" would
              mislead users into believing they could perform an HTTP request on
              a URL or put up a WebSocket client or server in a couple of lines of
              code. Where would the core utilities go? Very likely it would step
              on the owner of Boost.Asio's toes to put things in the boost/asio directory;
              at the very least, it would create unrequested, additional work for
              the foreign repository.
            </p>
<p>
              "Beast" is sufficiently vague as to not suggest any particular
              functionality, while acting as a memorable umbrella term for a family
              of low level containers and algorithms. People in the know or with
              a need for low-level network protocol operations will have no trouble
              finding it, and the chances of luring a novice into a bad experience
              are greatly reduced. There is precedent for proper names: "Hana",
              "Fusion", "Phoenix", and "Spirit" come
              to mind. Is "Beast" really any worse than say, "mp11"
              for example? Beast also already has a growing body of users and attention
              from the open source community, the name Beast comes up in reddit posts
              and StackOverflow as the answer to questions about which HTTP or WebSocket
              library to use.
            </p>
</dd>
<dt><span class="term"> "Some more advanced examples, e.g. including TLS with client/server
          certificates would help." </span></dt>
<dd><p>
              The server-framework example demonstrates how to implement a server
              that supports TLS using certificates. There are also websocket and
              HTTP client examples which use TLS. Furthermore, management of certificates
              is beyond the scope of the public interfaces of the library. Asio already
              provides documentation, interfaces, and examples for performing these
              tasks - Beast does not intend to reinvent them or to redundantly provide
              this information.
            </p></dd>
<dt><span class="term"> "A built-in HTTP router?" </span></dt>
<dd><p>
              We presume this means a facility to match expressions against the URI
              in HTTP requests, and dispatch them to calling code. The authors feel
              that this is a responsibility of higher level code. Beast does not
              try to offer a web server. That said, the server-framework example
              has a concept of request routing called a Service. Two services are
              provided, one for serving files and the other for handling WebSocket
              upgrade requests.
            </p></dd>
<dt><span class="term"> "HTTP Cookies? Forms/File Uploads?" </span></dt>
<dd><p>
              Cookies, or managing these types of HTTP headers in general, is the
              responsibility of higher levels. Beast just tries to get complete messages
              to and from the calling code. It deals in the HTTP headers just enough
              to process the message body and leaves the rest to callers. However,
              for forms and file uploads the symmetric interface of the message class
              allows HTTP requests to include arbitrary body types including those
              needed to upload a file or fill out a form.
            </p></dd>
<dt><span class="term"> "...supporting TLS (is this a feature? If not this would be
          a show-stopper), etc." </span></dt>
<dd><p>
              Beast works with the Stream concept, so it automatically works with
              the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span></code> that you have already set
              up through Asio.
            </p></dd>
<dt><span class="term"> "There should also be more examples of how to integrate the
          http service with getting files from the file system, generating responses
          CGI-style" </span></dt>
<dd>
<p>
              The design goal for the library is to not try to invent a web server.
              We feel that there is a strong need for a basic implementation that
              models the HTTP message and provides functions to send and receive
              them over Asio. Such an implementation should serve as a building block
              upon which higher abstractions such as the aforementioned HTTP service
              or cgi-gateway can be built.
            </p>
<p>
              There are several HTTP servers in the example directory which deliver
              files, as well as some tested and compiled code snippets which can
              be used as a starting point for interfacing with other processes.
            </p>
</dd>
<dt><span class="term"> "You should send a 100-continue to ask for the rest of the
          body if required." </span></dt>
<dd><p>
              Deciding on whether to send the "Expect: 100-continue" header
              or how to handle it on the server side is the caller's responsibility;
              Beast provides the functionality to send or inspect the header before
              sending or reading the body.
            </p></dd>
<dt><span class="term"> "I would also like to see instances of this library being used
          in production. That would give some evidence that the design works in practice."
          </span></dt>
<dd>
<p>
              Beast has already been on public servers receiving traffic and handling
              hundreds of millions of dollars' worth of financial transactions daily.
              The servers run <span class="bold"><strong>rippled</strong></span>, open source
              software (<a href="https://github.com/ripple/rippled" target="_top">repository</a>)
              implementing the <a href="https://ripple.com/files/ripple_consensus_whitepaper.pdf" target="_top"><span class="bold"><strong>Ripple Consensus Protocol</strong></span></a>, technology
              provided by <a href="http://ripple.com" target="_top">Ripple</a>.
            </p>
<p>
              Furthermore, the repository has grown significantly in popularity in
              2017. There are many users, and some of them participate directly in
              the repository by reporting issues, performing testing, and in some
              cases submitting pull requests with code contributions.
            </p>
</dd>
<dt><span class="term"> What about WebSocket message compression? </span></dt>
<dd><p>
              Beast WebSocket supports the permessage-deflate extension described
              in <a href="https://tools.ietf.org/html/draft-ietf-hybi-permessage-compression-00" target="_top">draft-ietf-hybi-permessage-compression-00</a>.
              The library comes with a header-only, C++11 port of ZLib's "deflate"
              codec used in the implementation of the permessage-deflate extension.
            </p></dd>
<dt><span class="term"> Where is the WebSocket TLS/SSL interface? </span></dt>
<dd>
<p>
              The <code class="computeroutput"><span class="identifier">websocket</span><span class="special">::</span><span class="identifier">stream</span></code> wraps the socket or stream
              that you provide (for example, a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span></code>
              or a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span></code>). You establish your TLS connection
              using the interface on <code class="computeroutput"><span class="identifier">ssl</span><span class="special">::</span><span class="identifier">stream</span></code>
              like shown in all of the Asio examples, then construct your <code class="computeroutput"><span class="identifier">websocket</span><span class="special">::</span><span class="identifier">stream</span></code> around it. It works perfectly
              fine; Beast comes with an <code class="computeroutput"><span class="identifier">ssl_stream</span></code>
              wrapper in the example directory which allows the SSL stream to be
              moved, overcoming an Asio limitation.
            </p>
<p>
              The WebSocket implementation <span class="bold"><strong>does</strong></span>
              provide support for shutting down the TLS connection through the use
              of the ADL compile-time virtual functions <a class="link" href="../ref/boost__beast__websocket__teardown.html" title="websocket::teardown"><code class="computeroutput"><span class="identifier">teardown</span></code></a> and <a class="link" href="../ref/boost__beast__websocket__async_teardown.html" title="websocket::async_teardown"><code class="computeroutput"><span class="identifier">async_teardown</span></code></a>. These will
              properly close the connection as per rfc6455 and overloads are available
              for TLS streams. Callers may provide their own overloads of these functions
              for user-defined next layer types.
            </p>
</dd>
</dl>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2016, 2017 Vinnie Falco<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="comparison_to_zaphoyd_studios_we.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../design_choices.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../release_notes.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
